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ABOUT THIS CHAPTER 


This chapter describes the Disk Initialization Package, which provides routines 
for initializing disks to be accessed with the File Manager and Disk Driver. A 
Single routine lets you easily present the standard user interface for 
initializing and naming a disk; the Standard File Package calls this routine 
when the user inserts an uninitialized disk. You can also use the Disk 
Initialization Package to perform each of the three steps of initializing a disk 
separately if desired. 


You should already be familiar with: 


the basic concepts and structures behind QuickDraw, particularly points 
the Toolbox Event Manager 

the File Manager 

packages in general, as discussed in the Package Manager chapter 


eee ie 
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USING THE DISK INITIALIZATION PACKAGE 


The Disk Initialization Package and the resources it uses are automatically read 
into memory from the system resource file when one of the routines in the 
package is called. Together, the package and its resources occupy about 5.3 
bytes. 


If the disk containing the system resource file isn't currently in a Macintosh 
disk drive, the user will be asked to switch disks and so may have to remove the 
one to be initialized. To avoid this, you can use the DILoad procedure, which 
explicitly reads the necessary resources into memory and makes them unpurgeable. 
You would need to call DILoad before explicitly ejecting the system disk or 
before any situations where it may be switched with another disk (except for 
situations handled by the Standard File Package, which calls DILoad itself). 


Note: The resources used by the Disk Initialization Package consist of a 
Single dialog and its associated items, even though the package may 
present what seem to be a number of different dialogs. A special 
technique is used to allow the single dialog to contain all possible 
dialog items with only some of them visible at one time. 


When you no longer need to have the Disk Initialization Package in memory, call 
DIUnload. The Standard File Package calls DIUnload before returning. 


When a disk-inserted event occurs, the system attempts to mount the volume (by 
calling the File Manager function MountVol) and returns MountVol's result code 
in the high-order word of the event message. In response to such an event, your 
application can examine the result code in the event message and call DIBadMount 
if an error occurred (that is, if the volume could not be mounted). If the error 
is one that can be corrected by initializing the disk, DIBadMount presents the 
standard user interface for initializing and naming the disk, and then mounts 
the volume itself. For other errors, it justs ejects the disk; these errors are 
rare, and may reflect a problem in your program. 


Note: Disk-inserted events during standard file saving and opening are 
handled by the Standard File Package. You'll call DIBadMount only 
in other, less common situations (for example, if your program 
explicitly ejects disks, or if you want to respond to the user's 
inserting an uninitialized disk when not expected). 


Disk initialization consists of three steps, each of which can be performed 
separately by the functions DIFormat, DIVerify, and DIZero. Normally you won't 
call these in a standard application, but they may be useful in special utility 
programs that have a nonstandard interface. 


Note: The remainder of this section describes the Disk Initialization Package 
on machines with the 128K or later ROM, as described in Volume IV. 


The Disk Initialization Package initializes disks, formatting the disk medium 
and placing the appropriate file directory structure on the disk. Earlier 
versions of the Disk Initialization Package format a 3 1/2—inch disk on a single 
side only, creating a 400K-byte volume and placing a flat file directory on the 
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disk. The new version of the Disk Initialization Package can format the 3 
1/2-inch disks on either one or both sides, creating 400K or 800K volumes 
respectively. It will format other devices (such as hard disks) as well; the 
size of volumes is determined by the driver for the particular device. 


When the 128K ROM version of the File Manager is present, all volumes except the 
400K, single-sided disks are automatically given hierarchical file directories. 
(Even the 400K disks can be given a hierarchical directory by holding down the 
option key.) If the 128K version of the File Manager is not present, all volumes 
are given flat file directories. 


The DIFormat function formats disks in single-sided disk drives as 400K volumes 
and disks in double-sided drives as 800K volumes; the size of all other volumes 
is determined by the driver for the particular device. 


The DIZero function places a flat file directory on disks in single-sided disk 
drives and a hierarchical file directory on disks in double-sided drives as 800K 
volumes. With all other devices, the type of directory placed on a volume is 
determined by the driver for the particular device. 


The DIBadMount function is called with the result code returned by MountVol as a 
parameter. Based on the value of this result code, on the type of drive 
containing the disk, and on the disk itself, DIBadMount decides what messages 
and buttons to display in its dialog box. 


The dialog displayed by DIBadMount gets its messages and buttons from a dialog 
item list ('DITL' resource -—6047). The new dialog item list contains messages 
and buttons for responding to all situations, but it's possible that a new Disk 
Initialization Package might run into an old dialog item list. The new Disk 
Initialization Package determines which item list it's using, and makes certain 
choices as to the best buttons and messages to display. 


If the user places a double-sided disk into a single-sided drive, MountVol 
returns ioErr. If there's a new item list, the message "This is a two-sided 
disk!" is displayed; if there's an old item list, the message "This disk is 
unreadable:" is used instead. 


If the user tries to erase or format a disk that's write-protected, and there's 
a new item list, the messages "Initialization failed!" and "This disk is write- 
protected!" will be displayed. If there's an old item list, the second message 
is omitted. 


If the user tries to erase or format a disk that's not ejectable, and there's a 
new item list, the Eject button that's normally displayed is replaced by a 
Cancel button. 


If the user tries to erase or format a disk in a double-sided drive, and 

there's a new item list, three buttons are displayed: Eject, One-sided, and 
Two-sided. If an old version of the item list is present, only two buttons are 
displayed: Eject and Initialize. If the user chooses the Initialize button, the 
disk is formatted as an 800K volume (and if the hierarchical version of the File 
Manager is present, a hierarchical file directory is written). 


If the user tries to erase or format a disk in a single-sided drive, only two 
buttons are displayed (regardless of which version of the Disk Initialization 
Package or item list is present): Eject and Initialize. If the user chooses the 
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Initialize button, the disk is formatted as a 400K, flat volume. With other 
types of devices, the user can choose to eject the volume or format it with a 
size determined by the driver. 


When the result code noErr is passed, DIBadMount can be used to reformat a 
valid, mounted volume without changing its name. This can be used, for instance, 
to change the format of a disk in a double-sided drive from single-sided to 
double-sided. If there's a new item list, your application can specify its own 
message using the Dialog Manager procedure ParamText; the message can be up to 
three lines long. The message is stored as the string "*“0". (Because the 
TextEdit procedure TextBox is used to display statText items, word wraparound is 
done automatically.) If there's an old item list, the message "Initialize this 
disk?" is displayed instead. 


Warning: If your application uses this call, it must call DILoad before 
ejecting the system disk. This will prevent accidental formatting 
of the system disk. 


Note: The volume to be reformatted must be mounted when DIBadMount is called. 


Formatting Hierarchical Volumes 


The Disk Initialization Package must set certain volume characteristics when 
placing a hierarchical file directory on a volume. Default values for these 
volume characteristics are stored in the 128K ROM; this section is for advanced 
programmers who want to substitute their own values. The record containing the 
default values, if defined in Pascal, would look like this: 


TYPE HFSDefaults = PACKED RECORD 


sigWord: ARRAY[1..2] OF CHAR; {signature word} 
abSize: LONGINT; {allocation block size in bytes} 
clpSize: LONGINT; {clump size in bytes} 
nxFreeFN: LONGINT; {next free file number} 
btClpSize: LONGINT; {B*-Tree clump size in bytes} 
rsrvl: INTEGER; {reserved} 
rsrv2: INTEGER; {reserved} 
rsrv3: INTEGER; {reserved} 

END; 


The default values for these fields are as follows: 


Field Default value 


sigWord 'BD' 
abSize 0 
clpSize 4 * abSize 


nxFreeFN 16 
btClpSize 0 


To supply your own values for these fields, create a similar, nonrelocatable 
record containing the desired values and place a pointer to it in the global 
variable FmtDefaults. To restore the system defaults, simply clear FmtDefaults. 
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The sigWord must equal 'BD' (meaning "big disk") for the volume to be recognized 
as a hierarchical volume. If the specified allocation block size is 0, the 
allocation block size is calculated according to the size of the volume: 

abSize = (1 + (volSize in blocks / 64K)) * 512 bytes 


If the specified B*-tree clump size is 0, the clump size for both the catalog 
and extent trees is calculated according to the size of the volume: 


btClpSize = (volSize in blocks)/128 * 512bytes 
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DISK INITIALIZATION PACKAGE ROUTINES 


Assembly-language note: The trap macro for the Disk Initialization Package 
is Pack2. The routine selectors are as follows: 


diBadMount .EQU 0 
diLoad . EQU 2 
diUnload . EQU 4 
diFormat . EQU 6 
diVerify .EQU 8 
diZero . EQU 10 


PROCEDURE DILoad; 


DILoad reads the Disk Initialization Package, and its associated dialog and 
dialog items, from the system resource file into memory and makes them 
unpurgeable. 


Note: DIFormat, DIVerify, and DIZero don't need the dialog, so if you use 
only these routines you can call the Resource Manager function 
GetResource to read just the package resource into memory (and 
the Memory Manager procedure HNoPurge to make it unpurgeable). 


PROCEDURE DIUnload; 


DIUnload makes the Disk Initialization Package (and its associated dialog and 
dialog items) purgeable. 


FUNCTION DIBadMount (where: Point; evtMessage: LONGINT) : INTEGER; 


Call DIBadMount when a disk-inserted event occurs if the result code in the 
high-order word of the associated event message indicates an error (that is, the 
result code is other than noErr). Given the event message in evtMessage, 
DIBadMount evaluates the result code and either ejects the disk or lets the user 
initialize and name it. The low-order word of the event message contains the 
drive number. The where parameter specifies the location (in global coordinates) 
of the top left corner of the dialog box displayed by DIBadMount. 


If the result code passed is extFSErr, memFullErr, nsDrvErr, paramErr, or 
volOnLinErr, DIBadMount simply ejects the disk from the drive and returns the 
result code. If the result code ioErr, badMDBErr, or noMacDskErr is passed, the 
error can be corrected by initializing the disk; DIBadMount displays a dialog 
box that describes the problem and asks whether the user wants to initialize the 
disk. For the result code ioErr, the dialog box shown in Figure 1 is displayed. 
(This happens if the disk is brand new.) For badMDBErr and noMacDskErr, 
DIBadMount displays a similar dialog box in which the description of the problem 
is "This disk is damaged" and "This is not a Macintosh disk", respectively. 
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This disk is unreadable: 


Do you want to initialize it? 


Figure 1—Disk Initialization Dialog for IOEn 


Figure 1—-Disk Initialization Dialog for I0Err 


Note: Before presenting the disk initialization dialog, DIBadMount checks 
whether the drive contains an already mounted volume; if so, it ejects 
the disk and returns 2 as its result. This will happen rarely and may 
reflect an error in your program (for example, you forgot to call 
DILoad and the user had to switch to the disk containing the system 
resource file). 


If the user responds to the disk initialization dialog by clicking the Eject 
button, DIBadMount ejects the disk and returns 1 as its result. If the 
Initialize button is clicked, a box displaying the message "Initializing 
disk..." appears, and DIBadMount attempts to initialize the disk. If 
initialization fails, the disk is ejected and the user is informed as shown in 
Figure 2; after the user clicks OK, DIBadMount returns a negative result code 
ranging from firstDskErr to lastDskErr, indicating that a low-level disk error 
occurred. 


Initialization failed! 


Figure 2-Initialization Failure Dialog 
Figure 2—Initialization Failure Dialog 


If the disk is successfully initialized, the dialog box in Figure 3 appears. 

After the user names the disk and clicks OK, DIBadMount mounts the volume by 

calling the File Manager function MountVol and returns MountVol's result code 
(noErr if no error occurs). 
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Please name this disk: 


Figure 3-Dialoz for Naming a Disk 
Figure 3—Dialog for Naming a Disk 


Result codes noErr No error 
extFSErr External file system 
memFullErr Not enough room in heap zone 
nsDrvErr No such drive 
paramErr Bad drive number 
volOnLinErr Volume already on-line 
firstDskErr Low-level disk error 


through lastDskErr 


Other results 1 User clicked Eject 
2 Mounted volume in drive 


FUNCTION DIFormat (drvNum: INTEGER) : OSErr; 


DIFormat formats the disk in the drive specified by the given drive number and 
returns a result code indicating whether the formatting was completed 
successfully or failed. Formatting a disk consists of writing special 
information onto it so that the Disk Driver can read from and write to the disk. 


Result codes noErr No error 
firstDskErr Low-level disk error 
through lastDskErr 


FUNCTION DIVerify (drvNum: INTEGER) : OSErr; 


DIVerify verifies the format of the disk in the drive specified by the given 
drive number; it reads each bit from the disk and returns a result code 
indicating whether all bits were read successfully or not. DIVerify doesn't 
affect the contents of the disk itself. 


Result codes noErr No error 
firstDskErr Low-level disk error 
through lastDskErr 

FUNCTION DiZero (drvNum: INTEGER; volName: Str255) : OSErr; 


On the unmounted volume in the drive specified by the given drive number, DIZero 
writes the volume information, a block map, and a file directory as for a volume 
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with no files; the volName parameter specifies the volume name to be included in 
the volume information. This is the last step in initialization 

(after formatting and verifying) and makes any files that are already on the 
volume permanently inaccessible. If the operation fails, DIZero returns a result 
code indicating that a low-level disk error occurred; otherwise, it mounts the 
volume by calling the File Manager function MountVol and returns MountVol's 
result code (noErr if no error occurs). 


Result codes noErr No error 
badMDBErr Bad master directory block 
extFSErr External file system 
ioErr I/O error 
memFullErr Not enough room in heap zone 
noMacDskErr Not a Macintosh disk 
nsDrvErr No such drive 
paramErr Bad drive number 
volOnLinErr Volume already on-line 
firstDskErr Low-level disk error 


through lastDskErr 
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SUMMARY OF THE DISK INITIALIZATION PACKAGE 


Routines 


PROCEDURE DILoad; 

PROCEDURE DIUnload; 

FUNCTION DIBadMount (where: Point; evtMessage: LONGINT) : INTEGER; 
FUNCTION DIFormat (drvNum: INTEGER) : OSErr; 

FUNCTION DIVerify (drvNum: INTEGER) : OSErr; 

FUNCTION DIZero (drvNum: INTEGER; volName: Str255) : OSErr; 


Result Codes 


Name Value Meaning 

badMDBErr —60 Bad master directory block 

extFSErr —58 External file system 

firstDskErr -84 First of the range of low-level disk errors 
ioErr —36 I/O error 

LastDskErr —64 Last of the range of low-level disk errors 
memFullErr  -—108 Not enough room in heap zone 

noErr 0 No error 

noMacDskErr -—57 Not a Macintosh disk 

nsDrvErr —56 No such drive 

paramErr —50 Bad drive number 

volOnLinErr —55 Volume already on-line 


Assembly-Language Information 
Constants 


» Routine selectors 


diBadMount .EQU 0 

diLoad . EQU 2 

diUnload . EQU 4 

diFormat . EQU 6 

diVerify . EQU 8 

diZero . EQU 10 

Variables 

FmtDefaults Pointer to substitute values for 


hierarchical volume characteristics [128K ROM] 
Trap Macro Name 


_Pack2 
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Further Reference: 


QuickDraw 

Toolbox Event Manager 

File Manager 

Package Manager 

Standard File Package 

Disk Driver 

Technical Note #70, Forcing Disks to be Either 400K or 800K 
"Macintosh Family Hardware Reference" 


END OF DOCUMENT 
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